📘 Khy-OS 文档站 🧭 新手先读:核心概念

元帅(Marshal)双模式任命与约束 — 实现报告

元帅(Marshal)双模式任命与约束 — 实现报告#

文档编号:IMPL-RPT-024
日期:2026-06-12
关联设计:[DESIGN-ARCH-024] khyos 元帅双模式任命与约束规范
关联测试:[TEST-RPT-008] 元帅双模式任命 — 测试报告


1. 目标#

闭环「主控模型(元帅)自动选举 ⇄ 用户强制指定」的矛盾:任何在线模型都能被任命为元帅,
且无论谁当元帅系统都稳定运行——强主放权、弱主上镣铐、连续失败可弹劾移交,全程不损坏项目文件、
不违背用户意志。

2. 改动清单#

2.1 新增(services/backend/src/services/marshal/,9 个纯模块)#

文件行为
capabilityVector.js层级→连续能力向量 + 加权分数 + 强/弱裁决(阈值 KHY_MARSHAL_STRONG_THRESHOLD,默认 65)
marshalAppointment.js双模式任命:electMarshal(reasoning 最高)/ appointMarshal(用户指定,防呆② 不在线即报错)
strategySOP.js预置战略库 6 意图(含 2 个只读逃生地板)+ buildChoiceSchema 闭枚举 + isLegalChoice 校验
ruleEngineGuard.js防呆① 二次校验:弱主 + 不可逆 + 未授权 → 降级须审批;红线硬拦截;逃生地板恒可行;强主 commit 豁免
weakMasterProtocol.js渲染选择题 Prompt(防呆③ 需求逐字围栏)+ extractFirstJson 解析 + 确定性单微步展开
strongMasterProtocol.js强主赋能:全权 / 跨级指挥 / 自我反省;精简 Prompt 原样接受自由计划
contextBaton.js无缝切换载体;businessRequest Object.defineProperty 冻结(防呆③);mutator 返回新接力棒
impeachment.js降级弹劾状态机;连续失败阈值(KHY_MARSHAL_IMPEACH_THRESHOLD,默认 2);逐字精确逼宫文案
index.jsMarshalCoordinator 编排——唯一对外集成面,再导出全部子模块

2.2 修改#

文件改动
platform/khy_platform/cli.py_run_claude_code_launcher 解析 --marshal <model> / --marshal=;_build_khy_proxy_env(marshal=…) 透传 KHY_MARSHAL;用法文档补一行。透传层不做能力封锁(用户意志至上)。

2.3 测试#

tests/services/marshal/marshalSubsystem.test.js(node:test,35 用例)。

3. 关键实现决策#

  1. 复用既有单一真源,零重复造轮:能力分层走 modelTier,可逆性走 reversibility,红线/活性走

constraintLattice,JSON 恢复走 safeJsonParse.extractFirstJson,拆解走 taskDecomposer(仅确定性策略)。

  1. 防呆落到代码而非仅 Prompt:
    • ① ruleEngineGuard.vetAction 对弱主不可逆动作返回 allowed:false, requiresApproval:true;
    • ② appointMarshal 对不在线指定返回 {error:'model_not_in_pool'};
    • ③ contextBaton 冻结 businessRequest,渲染器逐字嵌入;
    • ④ 全部为新文件,未触碰 toolUseLoop / 网关等核心业务逻辑。
  2. 零侵入接线:MarshalCoordinator 是唯一集成面,宿主按需接 KHY_MARSHAL;当前不强行改写核心循环

(依防呆④留作另行评审的可选增强)。

  1. 零硬编码:所有阈值带命名默认值 + 环境覆盖;选举确定性(并列按 reasoning→池序)。

4. 验证#

  • python3 -m py_compile platform/khy_platform/cli.py → OK。
  • node -e "require('./src/services/marshal')" → 9 导出全部加载。
  • node --test tests/services/marshal/marshalSubsystem.test.js → tests 35 / pass 35 / fail 0。
  • 既有 reversibility / constraintLattice 等模块未被修改,无回归面。

5. 现状#

目标 10 全部六阶段闭环;三场景(自动选举 / 强主指定 / 弱主指定)端到端跑通,含弹劾→无损移交。